Any folder in docs by a-zw · Pull Request #431 · eclipse-score/docs-as-code

a-zw · 2026-03-03T15:11:20Z

📌 Description

A proposal for a mechanism how to include other directories of the repo into documentation.

🚨 Impact Analysis

This change does not violate any tool requirements and is covered by existing tool requirements
This change does not violate any design decisions
Otherwise I have created a ticket for new tool qualification

✅ Checklist

Added/updated documentation for new or changed features
Added/updated tests to cover the changes
Followed project coding standards and guidelines

github-actions · 2026-03-03T15:12:06Z

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run //src:license-check

Status: ⚠️ Needs Review

Click to expand output

[License Check Output]
Extracting Bazel installation...
Starting local Bazel server (8.3.0) and connecting to it...
INFO: Invocation ID: 173cd95e-6a8d-46f2-8133-1a226753e0f6
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
Loading: 0 packages loaded
    currently loading: src
Loading: 0 packages loaded
    currently loading: src
Loading: 0 packages loaded
    currently loading: src
Analyzing: target //src:license-check (1 packages loaded, 0 targets configured)
Analyzing: target //src:license-check (1 packages loaded, 0 targets configured)

Analyzing: target //src:license-check (67 packages loaded, 9 targets configured)

Analyzing: target //src:license-check (68 packages loaded, 9 targets configured)

Analyzing: target //src:license-check (76 packages loaded, 9 targets configured)

Analyzing: target //src:license-check (128 packages loaded, 1475 targets configured)

Analyzing: target //src:license-check (132 packages loaded, 2516 targets configured)

Analyzing: target //src:license-check (140 packages loaded, 2576 targets configured)

Analyzing: target //src:license-check (140 packages loaded, 2576 targets configured)

Analyzing: target //src:license-check (140 packages loaded, 2576 targets configured)

Analyzing: target //src:license-check (140 packages loaded, 2576 targets configured)

Analyzing: target //src:license-check (144 packages loaded, 4589 targets configured)

INFO: Analyzed target //src:license-check (145 packages loaded, 4715 targets configured).
[9 / 16] Creating runfiles tree bazel-out/k8-opt-exec-ST-d57f47055a04/bin/external/score_tooling+/dash/tool/formatters/dash_format_converter.runfiles [for tool]; 0s local
[13 / 16] JavaToolchainCompileClasses external/rules_java+/toolchains/platformclasspath_classes; 0s disk-cache, processwrapper-sandbox
[14 / 16] JavaToolchainCompileBootClasspath external/rules_java+/toolchains/platformclasspath.jar; 0s disk-cache, processwrapper-sandbox
INFO: Found 1 target...
Target //src:license.check.license_check up-to-date:
  bazel-bin/src/license.check.license_check
  bazel-bin/src/license.check.license_check.jar
INFO: Elapsed time: 26.296s, Critical Path: 2.59s
INFO: 16 processes: 12 internal, 3 processwrapper-sandbox, 1 worker.
INFO: Build completed successfully, 16 total actions
INFO: Running command line: bazel-bin/src/license.check.license_check src/formatted.txt <args omitted>
usage: org.eclipse.dash.licenses.cli.Main [-batch <int>] [-cd <url>]
       [-confidence <int>] [-ef <url>] [-excludeSources <sources>] [-help] [-lic
       <url>] [-project <shortname>] [-repo <url>] [-review] [-summary <file>]
       [-timeout <seconds>] [-token <token>]

github-actions · 2026-03-03T15:16:59Z

The created documentation from the pull request is available at: docu-html

PiotrKorkus · 2026-03-04T09:34:06Z

Hello @a-zw,
thank you for that change that would be very helpful in reference_integration.

In my case the files I want to create a link to are generated during testing. In /docs static .rst files I would like to have a link to them. If testing was executed before and artifacts are in defined place the links should work. Otherwise I would expect docs build to be successful but the links to be broken.

Do you think it could work like this or some redesign is needed (around my idea or the tool itself)?

paulquiring

A needed addition to existing functionality.

paulquiring · 2026-03-04T09:21:25Z

docs/how-to/any_folder.rst

@@ -0,0 +1,29 @@
+Use Any Folder for Documentation
+=============================================


reduce to fit the headline

paulquiring · 2026-03-04T09:23:21Z

src/extensions/docs/index.rst

+   .. grid-item-card::
+
+      Any Folder
+      ^^^


Enlarge to fit the headline

paulquiring · 2026-03-04T09:47:14Z

docs/how-to/any_folder.rst

+Only relative links are allowed.
+
+The symlinks will show up in your sources.
+**Don't commit the symlinks to git!**


Would it be possible to crate the symlinks with a special pattern e.g.
docs/slt/component/containers/ // slt = symlink to
docs/slt/* could be added to the gitignore file.

I'm pretty sure that otherwise this would often be done incorrectly. One advantage for “free” is that it's clear which parts are outside the docs folder.

conf.py is Python code and all kinds of shenanigans are possible. Is there a benefit to do this within the extension?

docs/how-to/any_folder.rst

a-zw · 2026-03-04T10:20:19Z

Hello @a-zw, thank you for that change that would be very helpful in reference_integration.

In my case the files I want to create a link to are generated during testing. In /docs static .rst files I would like to have a link to them. If testing was executed before and artifacts are in defined place the links should work. Otherwise I would expect docs build to be successful but the links to be broken.

Do you think it could work like this or some redesign is needed (around my idea or the tool itself)?

This approach is not suitable to include Bazel build artifacts/dependencies. That would be the next logical step to me though, because then we could stop using sphinx-collections in the docs-combo build.

@PiotrKorkus Are these test results integrated build artifacts though? Alternatively, are they "sources" committed to git? Or is it just temporary artifacts creating in some GH workflows?

a-zw added 4 commits March 3, 2026 15:24

Add extension score_any_folder

7909bf2

Document any_folder extension

3245a50

dogfooding any_folder extension

5f001df

Fix warnings

e63570b

github-project-automation bot added this to INF - Infrastructure Community Mar 3, 2026

github-project-automation bot moved this to Draft in INF - Infrastructure Community Mar 3, 2026

a-zw mentioned this pull request Mar 3, 2026

Make source_dir = "module root folder" possible #429

Open

paulquiring reviewed Mar 4, 2026

View reviewed changes

docs/how-to/any_folder.rst Show resolved Hide resolved

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Any folder in docs#431

Any folder in docs#431
a-zw wants to merge 4 commits intoeclipse-score:mainfrom
etas-contrib:any_folder_in_docs

a-zw commented Mar 3, 2026

Uh oh!

github-actions bot commented Mar 3, 2026

Uh oh!

github-actions bot commented Mar 3, 2026

Uh oh!

PiotrKorkus commented Mar 4, 2026

Uh oh!

paulquiring left a comment

Uh oh!

paulquiring Mar 4, 2026 •

edited

Loading

Uh oh!

paulquiring Mar 4, 2026

Uh oh!

paulquiring Mar 4, 2026 •

edited

Loading

Uh oh!

a-zw Mar 4, 2026

Uh oh!

Uh oh!

a-zw commented Mar 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -0,0 +1,29 @@
		Use Any Folder for Documentation
		=============================================

Conversation

a-zw commented Mar 3, 2026

📌 Description

🚨 Impact Analysis

✅ Checklist

Uh oh!

github-actions bot commented Mar 3, 2026

License Check Results

Uh oh!

github-actions bot commented Mar 3, 2026

Uh oh!

PiotrKorkus commented Mar 4, 2026

Uh oh!

paulquiring left a comment

Choose a reason for hiding this comment

Uh oh!

paulquiring Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paulquiring Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

paulquiring Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

a-zw Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

a-zw commented Mar 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

paulquiring Mar 4, 2026 •

edited

Loading

paulquiring Mar 4, 2026 •

edited

Loading